home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 3: CDPD 3
/
Almathera Ten on Ten - Disc 3: CDPD3.iso
/
ab20
/
ab20_archive
/
utilities
/
file
/
whereis.lzh
/
whereis.doc
< prev
Wrap
Text File
|
1991-02-16
|
28KB
|
616 lines
--- whereis.doc --- Saturday 16/02/91
**************************************************************************
* whereis.doc (english) for whereis V1.22 (16-Feb-91) AMIGA-VERSION by *
* Roland Bless. All rights reserved. Doc lines: 615 *
* (C) 1989/90/91 by Byteable Software Products (Roland Bless) *
**************************************************************************
Yaffu? Yet another "find-that-file" utility? Nah, look at the features of
"whereis"! ;-)
Please read this documentation to inform yourself about:
1) What is "whereis" (good for)?
2) How is it used?
3) How it works.
4) What the error-messages mean.
Copyright/Distribution:
=======================
The program is FREEWARE (what else for this shabby stuff?) and should be
spread to any AMIGA-user around the world, because it is a utility that
saves time (esp. if you're using a harddisk, as I do!). Please distribute
or copy it ALWAYS with this documentation!
There are only two restrictions of distribution:
***************************************************************************
* This software may be distributed for non-profit only!! *
* No redistribution of a changed source and/or executable without the *
* permission of the author!!! Please ask me first. See address below.THANX*
***************************************************************************
About this documentation:
=========================
In some examples the quotation marks "" and '' must/need not to be typed.
They are only used to emphasize what you have to type in. Asterisks are
sometimes used to *emphasize* words.
Although there is a short info about the switches of "whereis", please read
this doc in its entirety to get the maximum benefit of this program. If
you're reading this in an editor or text-display program, you can jump to
the sections with searching for 1), 2), 3), or 4).
RELEASE HISTORY at the end of this document!!
German manual also available!
Overview of functions:
======================
Format:
whereis [-acdfijnpst] [dev:path] filepattern
Wildcards * and ? in the filepattern (strictly;-) allowed!
You can abort anytime with CTRL-D or CTRL-C.
Switches:
-a all. Same as -st, so date and size will be displayed.
-c CASE-SENSITIVE-Search
-d dirs only! Only directories are displayed.
-f files only! Files are displayed only, no directories!
-i Version-Info
-j jump into dir! Interactive "cd" function. If wanted, a "cd" will be
executed and the search aborts. Your current dir has changed.
-n no subdirectories! Subdirectories are not scanned.
(Doesn't make much sense, except for listing functions
(e.g. 'whereis -nfa "" *'))
-p Detailed pathnames! Displays detailed pathnames, if a path was given as an
argument.
-s sizes please! Displays sizes of the found files.
-t time & date! Displays date and time of last change of a file.
Format: dd-mm-yy hh:mm:ss (Day-Month-Year Hour:Minute:Second)
1) What is "whereis" (good for)?
=============================
"Whereis" is a utility which searches a file(name) on (hard)disk and shows
you the path to this file. Because AMIGA's power is only revealed if you've
installed a hard-disk (and AMIGA's commands are often loaded from disk
(c:-dir)), some hard-disk users (like me) will loose overview about the
stored files. If you have hundreds or thousands of subdirectories and don't
know in which of them the program "DiskSalv" was, just type in: "whereis
disksalv" and "whereis" will search through your whole active volume. You
don't have to look for with "list" or "dir" manually. All files matching
the given filename (-pattern) are displayed.
"Whereis" combines a "find that file"-function with certain list functions:
you can use it as "fnams/recurdir/mydir"[1] (or whatever that little
programs are called) to collect the filenames and give them to "ZOO" which
then can compress whole subdirectories or volumes. "Whereis" will do that
job savely for you!
** Note: "whereis" can only be started from a CLI or SHELL (sorry WB Users!).
[1] "RecurDir" or "mydir" (that's how the author (Stephen Vermeulen) named it)
was released on Fish-Disk 284. It is recursive programmed and 5516 Bytes long.
Features of "whereis":
======================
+ Case dependent/independent (switch -c).
+ Wildcards * and ? possible.
+ Abortable at any time (with CTRL-D or CTRL-C).
+ Interactive mode which allows to change your current dir.
+ Non recursive algorithm -> no problems with stack-sizes (not like LookFor or
RecurDir)
+ Works also as "fnams"/"RecurDir". Use "whereis" with pipes.
(archives all filenames from subdirectories for "ZOO", look below)
+ Can search on any file-oriented AmigaDOS-device and in any sub-dirs.
Can be used as a "list all".
+ Displays date and size of files if wanted.
+ some other useful options.
2) How to use "whereis":
=====================
If the program was not renamed, you can start it from CLI with:
whereis [-acdfijnpst] [dev:path] filename
The arguments in braces are optional that means they need not to be entered.
If "whereis" is called without any argument, it will display a hint for usage.
It doesn't matter where the options/switches are placed. All options/switches
are preceeded by a '-'-sign.
Another possibility to let "whereis" run, is to let it run in the background by
"run", "Arun" or "runback" and so on...(to abort it, when running in background,
just send via the "break" command the break-signal, e.g. "break 2 all").
To redirect the input/output is also allowed, but please note the '-j' switch,
which will always need an interactive input! If the input isn't interactive,
"whereis" will abort with "ERROR: Input must be interactive!".
And now something about the syntax:
-----------------------------------
If you enter "whereis filename", the searching for "filename" starts from the
root directory of your current active device/volume/partition. This "filename"
can contain the so called "wildcards" * and ? (therefore better "filepattern"
than "filename").
- wildcards: "*" stands for none, one or more character(s).
---------- (identical with #? in AMIGA-DOS)
"?" stands for just one character.
You can use multiple *s and ?s together!!
Examples:
*.info stands for all files containing .info at the end of their name.
*disk* stands for all files containing "disk" anywhere in their name.
?a* stands for all files containing an "a" as second character in
their name.
...and so on...
Please note a special behaviour:
Is there one or more ? at the *end* of the pattern, it is
possible that ? stands for *none* character, too!
For example: "a????" displays all files with an "a" as first
character and 5 characters AT MOST, but all files with less
than 5 characters in their name are displayed, too (so even 'a',
'ab','abc'...etc.)!
- pathnames:
----------
In addition to the necessary filename-pattern you can command "whereis"
in which directory it should look for. E.g. df0:,dh1:,usr:bin,/bin,include
and so on... It doesn't matter in which sequence filepattern and pathname
occur, because "whereis" is a little bit "intelligent"! To separate the
filepattern from the pathname there must be a ":" or a "/" in the path.
Otherwise "whereis" will always identify the first argument as pathname and
the second as filepattern! It is allowed to use "" for the current directory
and / for the parent directory or : for the root-dir of the current active
volume. You must enter the path separated from the filenamepattern, because it
would not make much sense to join them. Consider the following example:
"whereis dh1:test"
This looks like test were located in the root-dir of dh1:, but "test" is
possibly found in "dh1:usr/bin/"? If you recognize this conflict, please
don't be annoyed about this little extra space. If you nevertheless join
the path and searchpattern "whereis" will reply with: "ERROR: Please no
path in the filename/pattern! See usage!".
Examples:
"whereis usr:bin test" will search from "usr:bin" down through all sub-dirs
for "test" and is equivalent to "whereis test usr:bin"
"whereis bin/ test" will search in the directory "bin" (and downwards) for
test, if "bin" is a sub-directory of the current active
directory. Equivalent with
"whereis test bin/" and
"whereis bin test" .
*Not* equivalent would be "whereis test bin" (will
search for bin!).
"whereis df1: readme" searches for readme on df1:.
'whereis "" test' searches downwards from the current active directory
'whereis / test' searches downwards from the parent directory
'whereis : test' searches downwards from the root-directory
"whereis /// test" is also allowed!
- options/switches:
-----------------
switches are always preceeded by a '-'.
a: All. -a is equivalent to -st.
-a causes the output of size and date/time of the found files.
c: CASE-DEPENDENT or CASE-SENSITIVE.
-c instructs "whereis" to distinguish upper case from lower case letters.
The default value is not to distinguish.
d: Directories only! Only names of directories will be displayed.
f: Files only! The outprinted names are exclusively file- and *not*
directory-names. This option excludes '-d' and vice versa. If you use
'-df', the output will be none! (Doesn't make much sense, right?)
i: info. Prints the actual version-number of your version.
j: jump into dir!
This is an interactive useful option: If "whereis" finds a matching
filename it will prompt "Change to that dir? [yNq]:". Now you have three
possible responses:
y,Y: Yes, change the current directory of your cli or shell into that in
which "whereis" found that filename. If "whereis" displayed a dir-
name, it would change to that dir.
q,Q: Quit. Cancels the search ("whereis-- Aborted!") and you're back to
your current dir which was active before you started "whereis".
n,N: No, don't change the current dir (skip). Continues the search...!
All other Keys behave like n,N (therefore N is capitalized in [yNq]) and
continue the search.
Please note that this option is only active with an interactive standard-
input-device (You must be able to enter something!), otherwise "whereis"
will abort with an error message: "ERROR: Input must be interactive!", or
you'll just get the message "Change to that dir? [yNq]:", because the
standard-input was redirected. In this case, the best is, to cancel with q
or Q and start again without stdin redirected! Not allowed are e.g.:
"run whereis -j test" or "whereis <nil: -j test"
This option automatically activates '-p' (detailed pathnames).
n: No sub-directories!
Only the named directory is scanned and not the nested sub-directories.
If no directory/pathname was given, only the root-dir will be scanned.
This option may seem to contradict with the sense of "whereis", because
you seem already to know, where the file(s) is/are located. I just
considered the list-function of "whereis" and found out that in some rare
cases this may be helpful (think about "whereis : * -dn"; it will list all
branching directories from your root-dir).
p: Detailed pathnames!
Without any pathname as argument (e.g. whereis test) '-p' hasn't got any
effect, because "whereis" always displays the most detailed path, likewise
if the option '-j' is active (AmigaDOS does the same: if you enter "cd
usr:work", the "cd" will show the detailed path (e.g. MyHD1:usr/work) and
not "usr:work"!)
With a given pathname (e.g. whereis dh0:usr test) "whereis" (*without* the
option '-p' activated) displays the *short* path that means the path from
the given pathname to the found file and not the whole path from the root
directory to this file. This takes advantage of "assigned directories":
For example "etc:" is an assigned directory and is located in
"Rob-HD1:usr/etc". Supposing the file "test" is located in etc:, then '-p'
has got the following effect:
Input: Output:
"whereis etc: test" --> "etc:test"
"whereis -p etc: test" --> "Rob-HD1:usr/etc/test"
Supposing usr: is your current active directory, then you'll get this:
'whereis "" test' --> "etc/test"
'whereis -p "" test' --> "Rob-HD1:usr/etc/test"
If you activate the "LONGPATH"-option, the detailed path will be shown,
that means also "Rob-HD1:" instead of "dh1:".
s: Sizes (please)! The size of the found files is displayed. If "whereis"
displays a directory, "(dir)" is printed instead of a size value.
This option is helpful, if you have some versions of one program on your
hard-disk and you want to know, which versions are being displayed
(consider that new versions must not always be longer!). In this case use:
t: Time and date (please)! Date and time of the last change of the found file
are displayed. This is also useful to distinguish different versions of a
file (see also option '-a').
The format of the date is: dd-mm-yy hh:mm:ss
(day-month-year hours:minutes:seconds)
---
It is not (like in UNIX) of importance where you set the options:
whereis -c dh0: test
whereis dh0: -c test
whereis dh0: test -c
are all equivalent.
It doesn't matter either, whether the options stand alone or are encounted
behind one '-':
whereis -cfp usr: test
whereis -p usr: test -c -f
whereis -f usr: -p test -c
whereis -c -p -f usr: test
whereis test -pfc usr:
These calls are equivalent, too.
- "whereis" and PIPES: Forget "fnams"/"recurdir"!
-----------------------------------------------
The archive-program "ZOO" isn't able yet, to pack whole directories with their
sub-dirs (or whole volumes). Instead it has got an option I, which lets "ZOO"
read all filenames to compress from standard-input. To collect these filenames,
there were written some utilities (I got "fnams" and "recurdir" [1])
Both programs have got one great disadvantage: they work recursive! That
causes sometimes trouble with your STACK-size and then the GURU will visit
you. I prefer programs, which can run with a default stack-size of 4000 bytes.
Because for each program you need to change your STACK-size, maybe you'll get
confused (think of each process started from the shell with a huge stack-size:
this will eat up your memory! With 3MB I got enough, but I find it nasty to
waste memory!). So "whereis" allocates memory, instead of requiring large
stack-sizes, and naturally warns you and aborts correctly, if you run out of
memory. Recurdir just said goodbye after scanning 8 nested dirs (If you're
running UUCP-software, you'll soon get this depth) with a stack of 4000 bytes.
Note that recurdir/mydir is already 5516 Bytes large and recursive.
If you enter "whereis >usrdir -f usr: *", you can find the whole directory-tree
of usr: in the file "usrdir".
Ideal is the usage of "whereis" with pipes:
-------------------------------------------
Example for the ARP-Shell:
whereis -fp usr: * | zoo aI usrfiles
Normal Shell:
run whereis >pipe:files -fp usr: * +
run zoo <pipe:files aI usrfiles
This should run without any problems [2]!
You can get a sorted output in the ARP-Shell with:
whereis dh1: c* | sort
Because of this possibility I didn't implement a sort option...
[2]: Attention! The PIP: device from ARP 1.3 (it's the ConHandler from ConMan)
can guru! The bug is obviously caused by the ConHandler.library
V34.6, because other programs also lock up, but run fine with the
PIPE: device: e.g. type foo | sort (If foo is large enough,
sometimes the PIP: will lock up) Because of safety you should
perhaps prefer the PIPE:-device.
3) How "whereis works:
===================
"Whereis" scans all sub-directories branching from the named and displays files,
which match with the search-pattern on standard-output (STDOUT). "whereis" is
not programmed recursive and should not cause a stack overflow!
If an error occurs at execution, "whereis" will display an error-message on the
standard-error-output (STDERR). If you redirected STDOUT, the error-message will
appear on your CLI-Window and not in your output-file.
If you made a mistake and don't want to waste time, you can always abort the
scanning with: CTRL-d or CTRL-c
The message "*** BREAK ***" will follow.
BUT: The break-signal (CTRL-c/d) is only detected, if "whereis" climbs up one
directory. That means, if you let *display* "whereis" a lot of files (e.g.
"whereis c: *"), it may take a while to react and abort, but "whereis" will
ABORT ALWAYS! One CTRL-D is enough [3]! If there is not a lot of output, CTRL-c
will break as good as CTRL-D, but during output to the window it may react worse
than CTRL-D (try "whereis *"). Just a slight delay will be recognized during
normal use (not as a "list" command abused), and therefore no problems should
arouse. I decided in favour of sparing run-time to handle the break signal not
after each scanned entry, therefore you must accept this litte delay and
disadvantage. No advantage without a disadvantage...
The memory is freed decently at any abort caused by breaks or errors or the '-j'
interactive mode. Everytime "whereis" aborts with the message "-- Aborted!".
Everytime "-- Aborted!" appears, "whereis" returns an error code
(RETURN_ERROR=10). Sometimes other codes are returned.
[3]: A WARNING to all ConMan-Users (V1.3):
Seems only to concern conhandler.library V34.6:
If you press CTRL-c or CTRL-d to long, the machine will crash! That's
no bug of "whereis", but of ConMan V1.3. It took some time for me to
recognize that my setsignal-routines are ok. Using NEWCON: or (the
original) CON: you'll have no problems!
- How to use "whereis" more efficiently
-------------------------------------
Reduce, if possible, the directories that should be scanned!
Use "assigned directories": e.g. "whereis utils: disksalv"
The scan-time will be shortened, because to search a whole partition or
hard-disk will take a while (ca. 1 min for 20MBytes, depends strongly on your
"scan- speed"/"access-time" of your hard-drive!). Another possibility is, to
start "whereis" as a background-process, while you are working on other tasks
(what the hell is Multitasking else for?): e.g. "run whereis >T:found dh1:
*.c". Perhaps that is to use, if you can't restrict the search to a few
directories and must search the whole volume, but you want to continue your
work (write a text or program etc...).
4) What the error-messages mean:
=============================
Possible error-messages and their causes:
"FATAL ERROR: Not enough memory available!"
-------------------------------------------
Cause: Perhaps other programs allocated too much memory. "Whereis" needs
just a few bytes of memory to remember the directories, which type
of memory, FAST-, CHIP- or what else RAM, serves doesn't matter.
"ERROR: Can't find that directory or device:"
---------------------------------------------
Cause: Perhaps you mis-spelled the path. "Whereis" cannot get a "lock" on
this directory or device!
"ERROR: Destroyed entry! Couldn't examine this ' '. Very strange!"
------------------------------------------------------------------
Cause: I don't know either!...strange: "whereis" was able to get a "lock" on
the entry, but EXAMINE returned an error!
"ERROR: Can't handle so many arguments. See usage!"
---------------------------------------------------
Cause: You gave "whereis" more arguments than just the pattern and the path.
"ERROR: Please no path in the filename/pattern! See usage!"
-----------------------------------------------------------
Cause: You joined path and pattern! The filename contains a "/" or ":".
See section "How to use whereis - pathnames".
"ERROR: Illegal Option ' '!"
----------------------------
Cause: This option (all preceeded by the "-") is unknown to "whereis".
"ERROR: I've no filepattern to search for!"
-------------------------------------------
Cause: "whereis" always needs a filename/pattern to search for.
You only entered an option/switch.
"STRANGE ERROR: Something strange happend...!"
----------------------------------------------
Cause: While descending the directory-tree, "whereis" cannot get a "lock"
on a subdirectory. This error should *never* occur!
Another possibility is a fault during the CD, if you enable the
interactive mode (switch '-j').
"ERROR: Input must be interactive!"
-----------------------------------
Cause: This error occurs only in conjunction with the "-j" (interactive)
option. Perhaps you tried to run the interactive mode in background ("run
whereis -j ...") or you redirected the standard-input to a non input-
device ("whereis <t:tmp -j ..."). Please start again without "run" or "<".
Future enhancements?!
=====================
If you find this utility quite useful and better than all other "find-that-file"-
utilities, and if there are no "flames", I could add some features:
- a listing option. The output of date and size will then be formatted. Until
this option is implemented use "list" instead and pipes.
- search for date. Since/upto option like implemented in "list". In some cases
it would be useful to find the files again, which you used and got today or
yesterday or last week...
- A faster and more compact code (perhaps with help of assembler-routines).
I think this would produce much more speed, maybe about 5%. The speed
depends more on your hard-disk and controller!
A few words from the author...
==============================
I wrote this program, because I was fed up to look for programs with my
former "whereis/wo/findpath/find..." utilities:
All of them had aggravating deficiencies.
Either no case-independent search or not abortable, or to slow and now
wildcards :-(. Because I learned C, I thought of making it better (I hope
it succeeded...:-)! Because good literature is rare and I prefer the
English/American originals it wasn't easy to get the amiga under control...
I missed a good manual for the dos.library, but nevertheless the first
working version was ready after one week (I did the work a few hours each
day)...
In comparison with "LookFor" (distributed on Fish-Disk 274, Author: Mark
Schretlen, size: 11224 bytes), which doesn't offer any special options and
requires more stack than 4000 bytes, "whereis" was faster:
Scanning 3210 entries yielded on my system:
LookFor: 69.46 s [lookfor >nil: test on sc1:] 3 entries found
Whereis: 59.78 s [whereis >nil: sc1: test] 4 entries found
Find : 61.40 s [find >nil: sc1: -name test -print] 4 entries found
As you can see, the times of "find" and "whereis" are very similar. Perhaps
little differences are caused by caching in buffers or other side effects.
All programs were held and started from ram-disk.
BTW: "whereis" runs fine with 4000 bytes of stack. LookFor requires more stack.
The "LookFor" option "LookFor test on all" caused an error, because I
mounted the PIPE: device. LookFor couldn't manage this!
I don't want to annoy the authors of the "fnams|recurdir|mydir" utilities, but
"whereis" combines *two* functions in one program! ;-)
Play with "whereis" and it's features and perhaps you'll discover new
applications.
I hope that this utility will be placed in every programmers utility-dir to
make it easier for their work (Hi Matt?:-).
** Have Fun! **
Best wishes,
Roland Bless
P.S.: I want to thank Matt Dillon for his great DME! Thanx Matt!
All others, please excuse my poor English, but it isn't my
native language. I will welcome some hints about shabby faults.
--------------------------------------------------------------------------------
RELEASE-HISTORY:
----------------
V1.14 : First released ;-) version of "whereis".
KNOWN BUGS: Requires FAST-RAM. Doesn't run with NOFASTMEM!
V1.14a: Fixed the bug of V1.14.
NOT RELEASED.
V1.15: Some new useful options/switches.
-a, -s, -t, -f, -d, -p -n
KNOWN BUGS: -a Option (forgot a break ...:-).
NOT RELEASED.
V1.16: Source optimized: minimal faster, but less Code than in V1.15.
Bug fixed (-a option). Errorhandling completed:
No filepattern to search for...
KNOWN BUGS: If there is not enough free memory, "whereis" would
abort with an error message, but the allocated memory
won't be freed correctly.
Fixed in versions since 26-11-89.
Wildcard-handling improved: "*?*??*a*c" etc. is now perfect!
V1.16a: A BUG in the wildcard-handling fixed:
Filenames with a space in it, were not displayed, if the '*'-wildcard
was selected. Really a subtle bug! Didn't occur when the -c option was
active, because then toupper() was not used.
(Note: 0x020 & 0x5f == '\0')
I found this bug by accident (do you often have files with a space
in their name? I don't!)
ALL versions till V1.16a (inclusive) were released just in a few bbs in
germany (FRG).
V1.17: -j option added.
-p switch changed! (see option -p).
Checked the break-behaviour. All ok.
KNOWN BUGS: The CD to a volume killed the ":" at the end of its name.
That was not like AmigaDOS did.
V1.18 The little bug of 1.17 corrected. CD should work now.
KNOWN BUGS: Version (15-2-90)
yes, only the executable was buggy, because I linked
some obscure _exit and _main modules to it. One BUG
was that "whereis" did not leave your memory clean.
Just a few bytes, about 20, were not freed.
The second BUG: The return-code was wrong if all went ok.
Instead of returning twice 0, some crazy
values were returned.
If you recompiled the source with +L (long integers) these
bugs would not have occured. Sorry, I think the source is
and was clean! My fault: I didn't test it hard enough!!!!
V1.18 (27-2-90)
Just a new executable. Source was not changed. See KNOWN BUGS above.
V1.19 (25-05-90)
New wildcard-routine. The old one was not correct! Try to search for a
string like this: "A*bak*" would not match "Abatch.bak", because the "b"
occurs the first time in "batch" and "bat" doesn't match "bak". But this
is now corrected! Maybe it is now faster code...if you've got any trouble
with pattern matching, please let me know!
V1.20 (14-06-90)
Killed chkabort-routine. No bug fixes.
V1.21 (07-01-91)
Bug fixed in date-routine. (01-01-XX)
V1.22 (16-02-91)
Bug fixed in Match() routine. Could have caused endless loops at
certain wildcard combinations (e.g. "* foobar").
------------------------+---------------------------------------------------+
R o l a n d B l e s s |Internet: rob@spirits.ka.sub.org |
|BITNET: UKG5@DKAUNI2.BITNET |
Kriegsstrasse 129 |FAX: +49211623818 BTX:0211623818-0001|
7500 Karlsruhe - FRG |---------spirits--in--the--material--world---------|
voice +49 721 857328 |"They built machines that they can't control" STING|
------------------------+---------------------------------------------------+